Pluspack 1/Caligari Corporation Pluspack1 1998.iso/TSX_SDK/tsxINC/tsxAnim.h

C/C++ Source or Header | 1998-01-28 | 17.0 KB | 383 lines

//******************************************************************************
//    File: tsxAnim.h
//  Module: trueSpace eXtensions API
//   Descr: Animation
//******************************************************************************

#ifndef TSXANIM_H
#define TSXANIM_H

//------------------------------------------------------------------------------
//    Misc
//------------------------------------------------------------------------------

enum tsxKFRAME_TYPE {
    e_tsxKFT_UNDEF = 0,    // undefined
    e_tsxKFT_LOOK,        // look at object or ahead (valid only for tsxGNODE types)
    e_tsxKFT_ROTATE,    // object rotate (valid only for tsxGNODE types)
    e_tsxKFT_MOVE,        // object move (valid only for tsxGNODE types)
    e_tsxKFT_SCALE,        // object scale (valid only for tsxGNODE types)
    e_tsxKFT_DEFORM,    // object deformation (valid only for tsxLATTICE type)
    e_tsxKFT_RECT,        // material rectangle position and siza in UV space (valid only for tsxMATRECT type)
    e_tsxKFT_COLOR,        // color of material (valid only for tsxMATERIAL type)
    e_tsxKFT_SURFACE,   // shader of material (valid only for tsxMATERIAL type)
    e_tsxKFT_BUMP,        // bump mapping of material (valid only for tsxMATERIAL type)
    e_tsxKFT_TEXTURE,   // texture mapping of material (valid only for tsxMATERIAL type)
    e_tsxKFT_PROCTEX,   // procedural texture of material (valid only for tsxMATERIAL type)
    e_tsxKFT_ENVIRON,   // environment mapping of material (valid only for tsxMATERIAL type)
    e_tsxKFT_FACETCOS,  // autofacet angle of material (valid only for tsxMATERIAL type)
    e_tsxKFT_LCOLOR,    // color of light (valid only for tsxLIGHT type)
    e_tsxKFT_BACKGROUND,// background (valid only for tsxSCENE type)
    e_tsxKFT_GLOBENV,   // global environment (valid only for tsxSCENE type)
    e_tsxKFT_FOG,        // fog (valid only for tsxSCENE type)
    e_tsxKFT_RAYTRACE,  // raytrace refraction (valid only for tsxSCENE type)
    e_tsxKFT_PLUGIN,    // Photoshop plugin (valid only for tsxPLUGIN type)
    e_tsxKFT_NAIL,        // position of nail (valid only for tsxNAIL type)
    e_tsxKFT_JOINT,        // joint parameters (valid only for tsxJOINT type)
    e_tsxKFT_KINEMATICS,// inverse kinematics (valid only for tsxGROUP type)
    e_tsxKFT_VERTEX,    // vertex move (valid only for tsxPOLYHEDRON type)
    e_tsxKFT_INVISIBLE,    // invisibility (valid only for tsxPOLYHEDRON and tsxGROUP types)
    e_tsxKFT_END,
    };


//------------------------------------------------------------------------------
//    Managers
//------------------------------------------------------------------------------

// Creates and attaches a Script, if none present.
TSXAPIFN tsxERR tsxSobjCreateScript( tsxSOBJ* pSobj );
// Creates and attaches a Script, if none present.
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeCreateScript( tsxGNODE* pGNode );

// Creates and attaches a Script, if none present for object and all its children
TSXAPIFN tsxERR tsxSobjTreeCreateScript( tsxSOBJ* pSobj );
// Creates and attaches a Script, if none present for object and all its children
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeCreateScriptTree( tsxGNODE* pGNode );


// Deletes animation for the object
TSXAPIFN tsxERR tsxSobjDeleteScript( tsxSOBJ* pSobj );
// Deletes animation for the object
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeDeleteScript( tsxGNODE* pGNode );

// Deletes animation for for object and all its children
TSXAPIFN tsxERR tsxSobjTreeDeleteScript( tsxSOBJ* pSobj );
// Deletes animation for for object and all its children
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeDeleteScriptTree( tsxGNODE* pGNode );


// Copies animation of From object to destination To object
TSXAPIFN tsxERR tsxSobjCopyScript( tsxSOBJ* pSobjTo, tsxSOBJ* pSobjFrom );
// Copies animation of From object to destination To object
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeCopyScript( tsxGNODE* pGNodeTo, tsxGNODE* pGNodeFrom );


// Tests for an empty animation of the object
TSXAPIFN tsxBOOL tsxSobjEmptyScript( tsxSOBJ* pSobj );

// Tests for an empty animation of the object and all its children
TSXAPIFN tsxBOOL tsxSobjTreeEmptyScript( tsxSOBJ* pSobj );


//------------------------------------------------------------------------------
//    Active Time
//------------------------------------------------------------------------------


enum tsxANIM_PLAYMODE {
    e_tsxPLAY_SCENE,    // Update whole scene when ActiveTime changed.
    e_tsxPLAY_OBJECT,    // Update only selected object when ActiveTime changed.
};

// Set the active frame number for pGNode, related preparation.
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
// Although it says that it sets frame number for specified GNode,
// it only changes the active frame number indicator without any change
// of GNode.
TSXAPIFN void tsxAnimSetActiveFrame( tsxGNODE* pGNode, float frameNbr );

// Set the active frame number.
// It updates whole scene according the new frame number. If there is an
// animated object in the scene, it may be changed to correspond its keyframes.
// So if an eXtension is animating the Sobj, it should repeat following three
// steps:
// 1/ set the active frame number,
// 2/ change animated attribute of Sobj (i.e. its position),
// 3/ create keyframe of the attribute in active frame number (see below).
TSXAPIFN void tsxAnimSetActiveTime( float frameNbr );

// Get the active frame number.
TSXAPIFN float tsxAnimGetActiveTime( void );

// Specify callback function for a change of the active frame number.
// The function `func' will get called each time there is a change in the
// frame number, made by the normal trueSpace animation panels or through a
// call to one of the above functions for setting active time. Use 0 (NULL)
// to remove an installed callback.
// Returns the previous callback function pointer (or 0 if none).
TSXAPIFN tsxBasicCallbackFP tsxActiveTimeChangedCB(
    int tsxid,            // Id of this eXtn (see tsxGetData).
    tsxBasicCallbackFP func    // This function gets installed as the callback.
    );

// Set ranges for playback.
TSXAPIFN void tsxAnimSetPlayRanges( float start, float end );

// Get ranges for playback.
TSXAPIFN void tsxAnimGetPlayRanges( float* start, float* end );

// Set mode for playback.
TSXAPIFN void tsxAnimSetPlayMode( tsxANIM_PLAYMODE mode );

// Get mode for playback.
TSXAPIFN tsxANIM_PLAYMODE tsxAnimGetPlayMode( void );

// Run playback.
TSXAPIFN tsxERR tsxAnimPlay( void );

// Get base framerate.
TSXAPIFN float tsxAnimGetBaseFramerate(void);


//------------------------------------------------------------------------------
//    Animating.
//------------------------------------------------------------------------------

// Create Keyframe (at curr active frame nbr) for obj, for specified attributes.
TSXAPIFN tsxERR tsxSobjSetFrame( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );
// Create Keyframe (at curr active frame nbr) for obj, for specified attributes.
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeSetFrame( tsxGNODE* pGNode, tsxKFRAME_TYPE keyfType );

// Delete Keyframe (at curr active frame nbr) for obj, for specified attributes.
TSXAPIFN tsxERR tsxSobjUnsetFrame( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );
// Delete Keyframe (at curr active frame nbr) for obj, for specified attributes.
// Obsolete for tS3.1 and later versions, kept for compatibility with tS3.0
TSXAPIFN tsxERR tsxGNodeUnsetFrame( tsxGNODE* pGNode, tsxKFRAME_TYPE keyfType );


//------------------------------------------------------------------------------
//    Key Frames - Time.
//------------------------------------------------------------------------------

// Get time of the first frame for specified attribute if it exists (otherwise -1).
TSXAPIFN float tsxSobjGetFirstTime( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );

// Get time of the last frame for specified attribute if it exists (otherwise -1).
TSXAPIFN float tsxSobjGetLastTime( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );

// Get time of the next frame for specified attribute if it exists (otherwise -1).
TSXAPIFN float tsxSobjGetNextTime( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, float time );

// Get time of the previous frame for specified attribute if it exists (otherwise -1).
TSXAPIFN float tsxSobjGetPrevTime( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, float time );

// Get time of the closest next frame for specified attribute for whole tree if it exists (otherwise -1).
TSXAPIFN float tsxSobjTreeGetNextTime( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, float time );

// Get time of the closest previous frame for specified attribute for whole tree if it exists (otherwise -1).
TSXAPIFN float tsxSobjTreeGetPrevTime( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, float time );

// Get time ranges of whole animation of Sobj.
TSXAPIFN tsxERR tsxSobjGetMinMaxTime( tsxSOBJ* pSobj, float* min, float* max );

// Get time ranges of whole animation of Sobj and all its children.
TSXAPIFN tsxERR tsxSobjTreeGetMinMaxTime( tsxSOBJ* pSobj, float* min, float* max );

//------------------------------------------------------------------------------
//    Key Frames - Managers.
//------------------------------------------------------------------------------

// Create Keyframe for specified attribute.
TSXAPIFN tsxERR tsxFrameCreate( tsxKEYFRAME** ppKFrame, tsxKFRAME_TYPE keyfType );

// Delete Keyframe.
TSXAPIFN void tsxFrameDelete( tsxKEYFRAME* pKFrame );

// Get attribute of Keyframe.
TSXAPIFN tsxKFRAME_TYPE tsxFrameGetType( tsxKEYFRAME* pKFrame );

// Get name of attribute.
TSXAPIFN const char* tsxAnimGetTypeName( tsxKFRAME_TYPE keyfType );

// Copy Keyframe.
TSXAPIFN tsxERR tsxFrameCopy( tsxKEYFRAME* pKFrame, tsxKEYFRAME** ppKFrameCopy );

// Add Keyframe to obj, for specified attribute (and optional segment).
TSXAPIFN tsxERR tsxSobjInsertFrame( tsxSOBJ* pSobj, tsxKEYFRAME* pKFrame , long segment, float time );

// Remove Keyframe from whatever list it is in.
TSXAPIFN void tsxFrameRemove( tsxKEYFRAME* pKFrame );

// Get first Keyframe of obj, for specified attribute (and optional segment).
TSXAPIFN tsxKEYFRAME* tsxSobjGetFirstFrame( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, long segment );

// Get last Keyframe of obj, for specified attribute (and optional segment).
TSXAPIFN tsxKEYFRAME* tsxSobjGetLastFrame( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, long segment );

// Get Keyframe at specified time for specified attribute (and optional segment) if it exists.
TSXAPIFN tsxKEYFRAME* tsxSobjGetFrame( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, long segment, float time );

// Get closest previous (to specified time) Keyframe of obj, for specified attribute (and optional segment).
TSXAPIFN tsxKEYFRAME* tsxSobjGetLeftFrame( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, long segment, float time );

// Get next Keyframe.
TSXAPIFN tsxKEYFRAME* tsxFrameGetNextFrame( tsxKEYFRAME* pKFrame );

// Get previous Keyframe.
TSXAPIFN tsxKEYFRAME* tsxFrameGetPrevFrame( tsxKEYFRAME* pKFrame );

// Get frame number of Keyframe.
TSXAPIFN float tsxFrameGetTime( tsxKEYFRAME* pKFrame );

// There is no symmetrical routine: tsxFrameSetTime
// To change the time (frame number) of the keyframe use tsxSobjInsertFrame with desired time.
// It removes the keyframe from current place and inserts it to proper place to keep
// all keyframes sorted by time.


//------------------------------------------------------------------------------
//    Key Frames - Data.
//------------------------------------------------------------------------------

// Get spline parameters of Keyframe.
TSXAPIFN tsxERR tsxFrameGetSplineParameters( tsxKEYFRAME* pKFrame, float* continuity, float* tension, float* bias );

// Set spline parameters of Keyframe.
TSXAPIFN tsxERR tsxFrameSetSplineParameters( tsxKEYFRAME* pKFrame, float continuity, float tension, float bias );

// Get length of Keyframe data.
TSXAPIFN long tsxFrameGetDataLength( tsxKEYFRAME* pKFrame );

// Get description of Keyframe data. Returns size of description.
TSXAPIFN long tsxFrameGetDataDescription( tsxKEYFRAME* pKFrame, short** ppDescr );

// Get Keyframe data.
TSXAPIFN long tsxFrameGetData( tsxKEYFRAME* pKFrame, void* pData, long length );

// Set Keyframe data.
TSXAPIFN long tsxFrameSetData( tsxKEYFRAME* pKFrame, void* pData, long length );

// Get interpolated data for specified attribute (and optional segment) at specified time.
TSXAPIFN long tsxSobjGetInterpolatedData( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, long segment,
                                                    float time, void* pData, long length );



//------------------------------------------------------------------------------
//    Animating Custom Attributes
//------------------------------------------------------------------------------

// Function for extAnimSetOriginCB and extAnimPutOriginCB.
typedef tsxERR (*tsxAnimOriginCallbackFP)( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType);

// Function for extAnimSetFrameCB, extAnimUnSetFrameCB and extAnimPutFrameCB.
typedef tsxERR (*tsxAnimFrameCallbackFP)( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, float time);

typedef struct {
    // To store original value of Attribute of Sobj (may not be specified).
    tsxAnimOriginCallbackFP        extAnimSetOriginCB;
    // To restore original value of Attribute of Sobj (may not be specified).
    tsxAnimOriginCallbackFP        extAnimPutOriginCB;
    // To create Keyframe(s) of keyfType for Sobj at specified time.
    tsxAnimFrameCallbackFP        extAnimSetFrameCB;
    // To delete Keyframe(s) of keyfType for Sobj at specified time (may not be specified).
    tsxAnimFrameCallbackFP        extAnimUnSetFrameCB;
    // To update Attribute of Sobj according Keyframes of keyfType at specified time.
    tsxAnimFrameCallbackFP        extAnimPutFrameCB;
} tsxAnimCallbackFP;

// Register an attribute among attributes that may be animated.
TSXAPIFN tsxKFRAME_TYPE tsxAnimCreateAttribute(
    int tsxid,                            // eXtension id
    char* name,                            // name of the attribute (max 16 characters)
    tsxAnimCallbackFP* attrCallback,    // callback functions for the attribute
    long attrDataLength,                // length of stored original data (may be 0L)
    short* kfDataDescription,            // description of keyframe data (see below)
    long kfDataDescriptionSize            // length of description array
    );

// Allow an animation of specified attribute for Sobj.
TSXAPIFN tsxERR tsxSobjAddAttribute( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );

// Get the first attribute of Sobj.
TSXAPIFN tsxKFRAME_TYPE tsxSobjGetFirstAttribute( tsxSOBJ* pSobj );

// Get the next attribute of Sobj.
TSXAPIFN tsxKFRAME_TYPE tsxSobjGetNextAttribute( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );

// Test for attribute of Sobj.
TSXAPIFN tsxBOOL tsxSobjHasAttribute( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );

// Get the first segment of attribute of Sobj.
TSXAPIFN long tsxSobjGetFirstSegment( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType );

// Get the next segment of attribute of Sobj.
TSXAPIFN long tsxSobjGetNextSegment( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, long segment );


// Attribute data descriptor

//------------------------------------------------------------------------
// Descriptor for allowing attribute to animate over time. A structure of
// this type is added with each attribute that the eXtension animates to
// describe the data structure of its parameters. Specify pdOpaque for any
// non-scalar data in the record, or data that you don't want trueSpace to
// interpolate for you. Make the DataDescription describe all the bytes of
// the parameter block.
//-----------------------------------------------------------------------
// Specifies the type of the data

#define    pdOpaque 0x0000
// Opaque, meaning don't interpolate this. Followed by count of bytes to skip
// with pdOpaque, eg, pdOpaque, 4
// If it is followed by 0, it terminates the description.

#define    pdChar 0x0001
// Interpolate as signed byte

#define    pdShort 0x0002
// Interpolate as signed short

#define    pdLong 0x0003
// Interpolate as signed long

#define    pdUnsignedChar 0x0004
// Interpolate as unsigned byte

#define    pdUnsignedShort 0x0005
// Interpolate as unsigned short

#define    pdUnsignedLong 0x0006
// Interpolate as unsigned long

#define    pdDouble 0x0008
// Interpolate as a double

#define    pdFloat 0x0009
// Interpolate as a float


//------------------------------------------------------------------------------
//    Custom Attribute Original Data
//------------------------------------------------------------------------------

// Get length of Attribute data.
TSXAPIFN long tsxSobjGetAttrDataLength( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType);

// Get Attribute data.
TSXAPIFN long tsxSobjGetAttrData( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, void* pData, long length);

// Set Attribute data.
TSXAPIFN long tsxSobjSetAttrData( tsxSOBJ* pSobj, tsxKFRAME_TYPE keyfType, void* pData, long length);


//******************************************************************************
#endif // TSXANIM_H